.\" Copyright (c) 2011-2016 Yubico AB
.\" See the file COPYING for license statement.
.\"
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH yhsm-keystore-unlock "1" "December 2011" "python-pyhsm"

.SH NAME
yhsm-keystore-unlock \(hy Unlock the keystore in a YubiHSM

.SH SYNOPSIS
.B yhsm-keystore-unlock
[\fIoptions\fR]

.SH DESCRIPTION
In versions of the YubiHSM before 1.0, the YubiHSM could be protected
using a 'HSM password'. The YubiHSM would unlock it's cryptographic functions
if the correct password was given, but it was a simple comparison test.

In YubiHSM 1.0, the password was changed into an actual key that was used to
decrypt the contents of the YubiHSM internal key store, which was then AES-256
encrypted using the new 'Master key' when stored in the device.

In YubiHSM 1.0, the option to also require an YubiKey OTP to unlock the
keystore was also added. One or more 'Admin YubiKeys' can be configured
in the YubiHSM, and an OTP from one of these must also be provided before the
YubiHSM will enable it's cryptographic functions.

The OTP is simply validated against the non-encrypted internal database
(not key store) in the YubiHSM though, but together with a 'Master key' not
stored on the server with the YubiHSM, it provides enhanced security by being
a second factor that an attacker can't just intercept even if the server is
compromised.

.SH OPTIONS
.PP
.TP
\fB\-D\fR, \fB\-\-device\fR
device file name (default: /dev/ttyACM0).
.TP
\fB\-v\fR, \fB\-\-verbose\fR
enable verbose operation.
.TP
\fB\-\-debug\fR
enable debug printout, including all data sent to/from YubiHSM.
.TP
\fB\-\-no-otp\fR
skip the prompt for an OTP. For use by scripts where no OTP
is required and the Master Key is stored on the server with the YubiHSM.
.TP
\fB\-\-stdin\fR
read password and/or OTP from stdin rather than prompting for them.
Python prompts does not accept piped input, so this option have to be
used to unlock the YubiHSM from a script for example.

.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
.IP "\fB0\fR" 4
.IX Item "0"
YubiHSM keystore successfully unlocked.
.IP "\fB1\fR" 4
.IX Item "1"
Failed to unlock keystore.

.SH BUGS
Report python-pyhsm/yhsm-keystore-unlock bugs in
.URL "https://github.com/Yubico/python-pyhsm/issues/" "the issue tracker"

.SH "SEE ALSO"
The
.URL "https://developers.yubico.com/python-pyhsm/" "home page"
.PP
YubiHSMs can be obtained from
.URL "http://www.yubico.com/" "Yubico" "."
